<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title>calypso_card_session_c.html</title>
<!-- Source : c:/temp/calypso/calypso_card_session.c -->
<!-- Doc generated on Thu Jun 24 12:26:46 2010 by johann on PC_DEV_5 -->
<!-- Generated with ROBODoc Version 4.99.8 (Specific build by PRO ACTIVE - Apr 13 2010) -->
<style type="text/css">
body
{
  background-color: #ffffff;
  color: #000000;
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 9pt;
  margin-left: 60px;
  margin-right: 40px;  
}
table
{
  border-collapse: collapse;
  border-style: solid;
  border-width: 1px;
  border-color: #000000;
  margin-bottom: 12px;
}
td
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 9pt;
  vertical-align: top;
  padding-right: 6px;
  border-style: solid;
  border-width: 1px;
  border-color: #dddddd; 
}
th
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 9pt;
  vertical-align: top;  
  padding-right: 6px;
  border-style: solid;
  border-width: 1px;
  border-color: #000000;
  background-color: #dddddd;  
}
h1
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 18pt;
  font-weight: bold;
  margin-bottom: 36px;
  color: #000000;
  margin-left: -40px;
}
h2
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 12pt;
  font-weight: bold;
  margin-top: 48px;
  margin-bottom: 24px;
  padding-top: 2px;
  padding-bottom: 2px;
  background-color: #dddddd;
  color: #000000;
  margin-left: -40px;
}
h3
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 11pt;
  font-weight: bold;
  margin-top: 36px;
  margin-bottom: 24px; 
  border-style: none;
  border-top-style: solid;  
  border-width: 1px;
  border-color: #cccccc; 
  margin-left: -40px;
}
h4
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 11pt;
  font-weight: bold;
  margin-top: 24px;
  margin-bottom: 12px;  
}
h5
{
  font-family: Verdana, Geneva, Lucida, Arial, Helvetica, sans-serif;
  font-size: 9pt;
  font-weight: bold;
  margin-top: 12px;
  margin-bottom: 2px;  
}
a
{
  color: #0000ff;
}
p
{
  margin-top: 0px;
  margin-bottom: 6px;  
  width: 600px;
  text-align: justify;
}
ul
{
  margin-top: 0px;
  margin-bottom: 6px;  
  width: 600px;
  text-align: justify;
}
li
{
  margin-top: 0px;
  margin-bottom: 6px;  
  width: 550px;
  text-align: justify;
}
tt
{
  font-family: Courier, Courier New;
  font-size: 10pt;
}
pre
{
  background-color: #ffffff;
  color: #000000;
  font-size: 10pt;
}
.NAV
{
  font-size: 7pt;
}
a.NAV
{
  color: #0000cc;
}
.TOC
{
  font-size: 9pt;
  color: #888888;
}
a.TOC
{
  color: #0000ff;
}
.INDEX
{
  font-size: 9pt;
}
a.INDEX
{
  color: #0000ff;
}
.TYPE
{
  font-size: 7pt;
  color: #888888;
}
.ITEM
{
  font-weight: bold;
  color: #000088;
}
.LABEL
{
  color: #000088;
}
.HISTORY
{
  color: #006600;
}
.AUTHOR
{
  color: #006600;
}
.COPYRIGHT
{
  color: #006600;
}
.PORTABILITY
{
  color: #006600;
}
.WARNING
{
  color: #aa0000;
}

.bitinfo
{
  width: 60px;
  font-style: italic;
  text-align: center;
}

.bitnum
{
  text-align: center;
}

.bitname
{
  font-weight: bold;
  text-align: center;
}

.tabitem
{
  width: 100px;
}

.tabname
{
  width: 200px;
}

.tabdesc
{
  width: 450px;
}

.value
{
  font-family: courier;
  text-align: right;
}

.tabsepar
{
  border-top-style: solid;
  border-bottom-style: solid;
  border-width: 2px;
  border-color: #888888;
  font-style: italic;
  text-align: center;
}
</style>
</head>
<body bgcolor="#FFFFFF">
<a name="robo_top_of_doc"></a>
<h3 align="center">TABLE OF CONTENTS</h3>
<ul>
<li><a class="TOC" href="#robo6">calypso_card_session.c</a></li>
<li><a class="TOC" href="#robo95">CalypsoCardCloseSecureSession</a></li>
<li><a class="TOC" href="#robo96">CalypsoCardGetChallenge</a></li>
<li><a class="TOC" href="#robo98">CalypsoCardOpenSecureSession1</a></li>
<li><a class="TOC" href="#robo99">CalypsoCardOpenSecureSession2</a></li>
<li><a class="TOC" href="#robo100">CalypsoCardOpenSecureSession3</a></li>
<li><a class="TOC" href="#robo101">CalypsoCardOpenSecureSessionEx</a></li>
<li><a class="TOC" href="#robo109">CalypsoCardSendRatificationFrame</a></li>
</ul>
<h3>&nbsp;</h3>


<h1><a name="robo6"><span class="TYPE">[Modules]</span><a class="LABEL" name="calypso5fcard5fsession2ec">
calypso_card_session.c</a></h1>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./modules.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   SpringCard Calypso API :: Card command set (security and transactions)
</pre>
</span><p class="ITEM">COPYRIGHT</p>
<span class="COPYRIGHT"><pre class="COPYRIGHT">   (c) 2008 PRO ACTIVE SAS - See LICENCE.txt for licence information
</pre>
</span><p class="ITEM">AUTHOR</p>
<span class="AUTHOR"><pre class="AUTHOR">   Johann Dantant / PRO ACTIVE
</pre>
</span><p class="ITEM">HISTORY</p>
<span class="HISTORY"><pre class="HISTORY">   JDA 21/10/2008 : first public release
   JDA 04/01/2010 : implemented GetChallenge
</pre>
</span>


<h2><a name="robo95"><span class="TYPE">[Functions]</span><a class="LABEL" name="CalypsoCardCloseSecureSession">
CalypsoCardCloseSecureSession</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>CalypsoCardCloseSecureSession</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Close a secure session
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   CALYPSO_CTX_ST *ctx        : library context
   BOOL           ratify_now  : if set, the session is immediately ratified
   BYTE           sam_sign[4] : the signature provided by the Calypso SAM
   BYTE           resp[]      : buffer to receive the response
   BYTE           *respsize   : input  = size of the response buffer
                                output = actual length of the response
                                         (EXCLUDING the status word that must be 9000)
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   CALYPSO_RC                 : 0 or an error code
</pre>
</span><p class="ITEM">NOTES</p>
<span class="NOTES"><pre class="NOTES">   This function is only a command sent to the card.
   The response is not interpreted by this function. It is up to the caller to
   1. check that the returned content is valid
   2. ask the SAM to verify card's signature
   For an automated implementation, use <a class="LINK_23" href="./calypso_transaction_c.html#robo117">CalypsoCommitTransaction</a> instead.
</pre>
</span>


<h2><a name="robo96"><span class="TYPE">[Functions]</span><a class="LABEL" name="CalypsoCardGetChallenge">
CalypsoCardGetChallenge</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>CalypsoCardGetChallenge</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Ask the card to generate an 8-byte challenge
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   CALYPSO_CTX_ST *ctx          : library context
   BYTE           challenge[8]  : the challenge returned by the card
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   CALYPSO_RC                   : 0 or an error code
</pre>
</span><p class="ITEM">SEE ALSO</p>
<span class="SEE_ALSO"><pre class="SEE ALSO">   <a class="LINK_37" href="./calypso_sam_commands_c.html#robo124">CalypsoSamGiveRandom</a>
</pre>
</span>


<h2><a name="robo98"><span class="TYPE">[Functions]</span><a class="LABEL" name="CalypsoCardOpenSecureSession1">
CalypsoCardOpenSecureSession1</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>CalypsoCardOpenSecureSession1</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Open a secure session, Revision 1 implementation
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   CALYPSO_CTX_ST *ctx         : library context
   BYTE           resp[]       : buffer to receive the response
   CALYPSO_SZ     *respsize    : input  = size of the response buffer
                                 output = actual length of the response
                                          (EXCLUDING the status word that must be 9000)
   BYTE           key_no       : identifier of the cryptographic key
   BYTE           sfi          : identifier of the file to read (0 for current file)
   BYTE           rec_no       : identifier of the record to read (0 for none)
   const BYTE     sam_chal[4]  : challenge returned by the SAM (see <a class="LINK_12" href="./calypso_sam_commands_c.html#robo123">CalypsoSamGetChallenge</a>)
   BYTE           card_chal[4] : buffer to receive card's challenge
   BOOL           *ratified    : tells whether last card session was ratified or not
   BYTE           data[]       : buffer to receive record data (if some)
   CALYPSO_SZ     *datasize    : input  = size of the record data buffer
                                 output = actual length of record data
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   CALYPSO_RC                  : 0 or an error code
</pre>
</span>


<h2><a name="robo99"><span class="TYPE">[Functions]</span><a class="LABEL" name="CalypsoCardOpenSecureSession2">
CalypsoCardOpenSecureSession2</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>CalypsoCardOpenSecureSession2</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Open a secure session, Revision 2 implementation
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   CALYPSO_CTX_ST *ctx         : library context
   BYTE           resp[]       : buffer to receive the response
   CALYPSO_SZ     *respsize    : input  = size of the response buffer
                                 output = actual length of the response
                                          (EXCLUDING the status word that must be 9000)
   BYTE           key_no       : identifier of the cryptographic key
   BYTE           sfi          : identifier of the file to read (0 for current file)
   BYTE           rec_no       : identifier of the record to read (0 for none)
   const BYTE     sam_chal[4]  : challenge returned by the SAM (see <a class="LINK_12" href="./calypso_sam_commands_c.html#robo123">CalypsoSamGetChallenge</a>)
   BYTE           card_chal[4] : buffer to receive card's challenge
   BOOL           *ratified    : tells whether last card session was ratified or not
   BYTE           data[]       : buffer to receive record data (if some)
   CALYPSO_SZ     *datasize    : input  = size of the record data buffer
                                 output = actual length of record data
   BYTE           *kvc         : KVC specified by the card according to key_no
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   CALYPSO_RC                  : 0 or an error code
</pre>
</span>


<h2><a name="robo100"><span class="TYPE">[Functions]</span><a class="LABEL" name="CalypsoCardOpenSecureSession3">
CalypsoCardOpenSecureSession3</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>CalypsoCardOpenSecureSession3</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Open a secure session, Revision 3 implementation
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   CALYPSO_CTX_ST *ctx         : library context
   BYTE           resp[]       : buffer to receive the response
   CALYPSO_SZ     *respsize    : input  = size of the response buffer
                                 output = actual length of the response
                                          (EXCLUDING the status word that must be 9000)
   BYTE           key_no       : identifier of the cryptographic key
   BYTE           sfi          : identifier of the file to read (0 for current file)
   BYTE           rec_no       : identifier of the record to read (0 for none)
   const BYTE     sam_chal[4]  : challenge returned by the SAM (see <a class="LINK_12" href="./calypso_sam_commands_c.html#robo123">CalypsoSamGetChallenge</a>)
   BYTE           card_chal[4] : buffer to receive card's challenge
   BOOL           *ratified    : tells whether last card session was ratified or not
   BYTE           data[]       : buffer to receive record data (if some)
   CALYPSO_SZ     *datasize    : input  = size of the record data buffer
                                 output = actual length of record data
   BYTE           *kvc         : KVC specified by the card according to key_no
   BYTE           *kif         : KIF specified by the card according to key_no
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   CALYPSO_RC                  : 0 or an error code
</pre>
</span>


<h2><a name="robo101"><span class="TYPE">[Functions]</span><a class="LABEL" name="CalypsoCardOpenSecureSessionEx">
CalypsoCardOpenSecureSessionEx</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>CalypsoCardOpenSecureSessionEx</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Open a secure session on the card, with user-defined parameters
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   CALYPSO_CTX_ST *ctx        : library context
   BYTE           apdu_p1     : the P1 parameter
   BYTE           apdu_p2     : the P2 parameter
   BYTE           sam_chal[4] : the challenge provided by the Calypso SAM
                                     (see <a class="LINK_12" href="./calypso_sam_commands_c.html#robo125">CalypsoSamSelectDiversifier</a>)
   BYTE           resp[]      : buffer to receive the response
   BYTE           *respsize   : input  = size of the response buffer
                                    output = actual length of the response
                                             (EXCLUDING the status word that must be 9000)
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   CALYPSO_RC                 : 0 or an error code
</pre>
</span><p class="ITEM">NOTES</p>
<span class="NOTES"><pre class="NOTES">   This function is only a command sent to the card.
   The response is not interpreted by this function. It is up to the caller to
   1. check that the returned content is valid
   2. feed the SAM with card's challenge
   3. use <a class="LINK_23" href="./calypso_sam_commands_c.html#robo122">CalypsoSamDigestUpdate</a> to feed the SAM with future exchanges
   For an automated implementation, use <a class="LINK_23" href="./calypso_transaction_c.html#robo126">CalypsoStartTransaction</a> instead.
</pre>
</span>


<h2><a name="robo109"><span class="TYPE">[Functions]</span><a class="LABEL" name="CalypsoCardSendRatificationFrame">
CalypsoCardSendRatificationFrame</a></h2>

<p class="NAV">[<a class="NAV" href="#robo_top_of_doc">top</a>][<a class="NAV" href="./functions.html#top">index</a>]</p>
<p class="ITEM">NAME</p>
<span class="NAME"><pre class="NAME">   <strong>CalypsoCardSendRatificationFrame</strong>
</pre>
</span><p class="ITEM">DESCRIPTION</p>
<span class="DESCRIPTION"><pre class="DESCRIPTION">   Ask card to compute a challenge, specifying an invalid length
   (1 byte instead of 4). This command is used to ratify the session
   in a card not implementing the 'ratify on deselect' feature
</pre>
</span><p class="ITEM">INPUTS</p>
<span class="INPUTS"><pre class="INPUTS">   CALYPSO_CTX_ST *ctx : library context
</pre>
</span><p class="ITEM">RETURNS</p>
<span class="RETURNS"><pre class="RETURNS">   CALYPSO_RC          : 0 or an error code
</pre>
</span>
<hr />
Generated from <b>calypso_card_session.c</b> on Thu Jun 24 12:26:46 2010<br />
</body>
</html>
